---
id: TASK-010
title: 'TUI: Cache-age-aware initial refresh timer'
status: To Do
assignee: []
created_date: '2026-06-12 04:21'
labels:
  - tui
  - enhancement
dependencies: []
priority: medium
ordinal: 10000
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
On startup, the TUI always fires `refresh_data()` immediately even if the Next.js app's snapshots are only seconds old. Instead, read `refreshedAt` from each snapshot and compute how much of the TTL has already elapsed, then wait only the remaining time before the first refresh.

For example: if a source has a 5-minute TTL and its snapshot is 4 minutes old, the TUI should wait ~1 minute before its first fetch, not 5 minutes (or 0).

Implementation:
- After the initial `fetch_sources()` call, extract `min(refreshedAt)` or per-source `refreshedAt` from snapshots
- Compute `remaining = refresh_interval - (now - refreshedAt)`
- Schedule the first repeating timer to fire after `max(0, remaining)` seconds
- Fall back to immediate refresh if no snapshots exist
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 Restarting TUI with fresh data does not immediately re-fetch all sources
- [ ] #2 Restarting TUI with stale data fetches immediately
- [ ] #3 Logic degrades gracefully when refreshedAt is missing from snapshot
<!-- AC:END -->